Hermes MongoDB MCP 로컬 데몬 운영 가이드

1. 목적과 현재 구조

Hermes가 MongoDB를 조회할 때 연결 문자열을 모델의 도구 인자나 Hermes 터미널 환경에서 읽지 않도록 한다. MongoDB MCP 서버는 macOS 사용자 LaunchAgent로 실행하며, Hermes는 localhost의 MCP HTTP 엔드포인트만 호출한다.

Hermes agent
  -> http://127.0.0.1:39180/mcp
  -> MongoDB MCP daemon (LaunchAgent)
  -> macOS Keychain의 읽기 전용 MongoDB URI
  -> MongoDB

2026-07-31에 사용자 확인과 로컬 점검으로 다음 상태를 확인했다.

• LaunchAgent com.choiwheatley.hermes.mongodb-mcp가 running 상태다.
• MongoDB MCP Node 프로세스가 127.0.0.1:39180에서 수신 중이다.
• Hermes 설정은 stdio npx 실행이 아니라 http://127.0.0.1:39180/mcp를 사용한다.

2. 도입 배경

이전 구성은 Hermes가 stdio 방식으로 mongodb-mcp-server를 시작하고, MDB_MCP_CONNECTION_STRING을 Hermes 환경에서 MCP 자식 프로세스로 전달했다.

이 구조에는 두 문제가 있었다.

1. 연결이 없는 상태에서 모델이 실제 값이 아닌 문자열로 connect(connectionString)을 호출했다. DNS 오류가 발생했지만 MongoDB MCP는 이를 일반적인 "MongoDB에 연결해야 합니다" 오류로 반환해 원인 파악이 어려웠다.
2. Hermes 로컬 터미널은 영속 셸 스냅샷을 만든다. Hermes .env의 MongoDB 관련 값이 초기 환경에 있으면 스냅샷에도 남아, direnv가 현재 작업 트리에서 비활성인 경우에도 에이전트가 값을 읽을 수 있었다.

terminal.env_passthrough: []는 이 문제를 막는 설정이 아니다. 이는 샌드박스 환경의 허용 목록이며, 로컬 터미널을 비밀값 없는 환경으로 만드는 차단 목록이 아니다.

3. 구성 요소

데몬은 --readOnly, --disableServerSideJs, --telemetry disabled, --maxSessions 5로 실행한다. DB 사용자 자체도 읽기 전용 권한이어야 한다. MCP의 --readOnly 옵션만으로 DB 계정의 쓰기 권한을 대체하지 않는다.

4. 정상 운영 절차

4.1. 상태 확인

launchctl print "gui/$(id -u)/com.choiwheatley.hermes.mongodb-mcp"
lsof -nP -iTCP:39180 -sTCP:LISTEN
hermes mcp test mongodb

기대 결과:

• launchctl print에 state = running
• lsof에 127.0.0.1:39180 (LISTEN)
• hermes mcp test mongodb에서 HTTP MCP 도구 발견 성공

백엔드 연결은 새 Hermes 세션에서 mcp__mongodb__list_databases 같은 읽기 도구로 확인한다. 정상 구성에서는 connect를 호출하지 않는다. 설정된 연결 문자열이 MCP 데몬 내부에서 자동으로 사용된다.

4.2. Keychain 항목 교체

Keychain Access에서 로그인 키체인의 아래 항목을 갱신한다.

교체 뒤 데몬을 재기동한다.

launchctl kickstart -k "gui/$(id -u)/com.choiwheatley.hermes.mongodb-mcp"

5. 장애 대응

5.1. Hermes가 MCP 서버에 연결하지 못함

1. LaunchAgent와 포트를 확인한다.
2. 데몬 로그 ~/.hermes/logs/mongodb-mcp-daemon.log에서 Keychain 오류, 포트 점유, npm 실행 오류를 확인한다.
3. 데몬이 정상인데 Hermes가 이전 stdio 구성을 계속 사용하면 Hermes 게이트웨이 또는 MCP 도구 발견을 새로고침한다.
4. hermes mcp test mongodb로 서버 등록/도구 발견을 확인한 뒤, 실제 읽기 도구 한 번으로 DB 연결을 확인한다.

5.2. Keychain 항목을 찾지 못함

증상은 LaunchAgent가 짧은 주기로 재시작되고 데몬 로그에 Keychain 조회 실패가 남는 것이다.

• 로그인 키체인에 service 이름 hermes-mongodb-mcp-uri가 정확히 존재하는지 확인한다.
• Account가 LaunchAgent를 실행하는 macOS 사용자와 일치하는지 확인한다.
• Keychain Access 권한 대화상자가 보이면 허용 여부를 확인한다.
• 항목을 수정한 뒤 launchctl kickstart -k ...로 다시 시작한다.

5.3. MCP 호출이 일반적인 "연결 필요" 오류만 반환함

MongoDB MCP는 잘못된 연결 문자열이나 DNS 오류를 일반적인 미연결 오류로 바꿔 반환할 수 있다. 모델이 임의의 connectionString으로 재시도하거나 터미널에서 환경변수를 읽어 우회하면 안 된다.

점검 순서:

1. 데몬 로그에서 원래 오류를 확인한다.
2. Keychain 항목과 읽기 전용 DB 계정의 유효성을 운영자가 확인한다.
3. 데몬을 재기동한다.
4. hermes mcp test mongodb와 읽기 도구를 순서대로 다시 확인한다.

5.4. 포트 39180이 이미 사용 중임

lsof -nP -iTCP:39180 -sTCP:LISTEN

기존 MongoDB MCP 데몬이 아니라면 점유 프로세스를 중지하거나, 런처의 --httpPort와 Hermes mcp_servers.mongodb.url을 같은 새 포트로 함께 변경한다. 한쪽만 변경하면 Hermes가 다른 서버에 연결하거나 연결에 실패한다.

6. 보안 운영 기준

• MongoDB URI를 ~/.hermes/.env, Hermes profile .env, config.yaml, 작업 트리 .env.local에 복사하지 않는다.
• 기존 환경 파일에 남아 있던 MONGODB_URI 또는 MDB_MCP_CONNECTION_STRING은 제거한 뒤 Hermes 게이트웨이를 재시작한다. 영속 셸 스냅샷도 새로 생성되어야 한다.
• MCP는 반드시 127.0.0.1에만 바인딩한다. 0.0.0.0 또는 사설망 주소로 변경하지 않는다.
• MongoDB DB 사용자는 읽기 전용 역할로 발급한다. MCP 옵션과 DB 권한을 함께 방어선으로 사용한다.
• 에이전트는 연결 오류 이후 env, .env, direnv, mongosh로 우회하지 않는다. 원인을 보고하고 운영자가 Keychain·데몬을 점검한다.
• localhost MCP는 DB URI를 모델에 주지 않지만, MCP가 허용한 읽기 요청은 처리한다. 조회 범위와 DB 사용자 권한은 최소 권한으로 유지한다.

7. 변경·복구 절차

데몬을 처음 등록할 때

launchctl bootstrap "gui/$(id -u)" \
  "$HOME/Library/LaunchAgents/com.choiwheatley.hermes.mongodb-mcp.plist"
launchctl kickstart -k "gui/$(id -u)/com.choiwheatley.hermes.mongodb-mcp"

데몬을 제거할 때

launchctl bootout "gui/$(id -u)/com.choiwheatley.hermes.mongodb-mcp"

제거 후에는 Hermes 설정의 mcp_servers.mongodb를 함께 비활성화하거나 제거한다. 설정만 남기면 Hermes는 localhost 엔드포인트에 재연결을 반복한다.

8. 참고 경로

• ~/bin/mongodb-mcp-daemon
• ~/Library/LaunchAgents/com.choiwheatley.hermes.mongodb-mcp.plist
• ~/.hermes/config.yaml의 mcp_servers.mongodb
• ~/.hermes/logs/mongodb-mcp-daemon.log
• Bash, Zsh 환경변수 설정 - export 사용 여부의 차이